2.1 Argument Lists

Emacs Lisp’s notation for argument lists of functions is a subset of the Common Lisp notation. As well as the familiar &optional and &rest markers, Common Lisp allows you to specify default values for optional arguments, and it provides the additional markers &key and &aux.

Since argument parsing is built-in to Emacs, there is no way for this package to implement Common Lisp argument lists seamlessly. Instead, this package defines alternates for several Lisp forms which you must use if you need Common Lisp argument lists.

Macro: cl-defun name arglist body…

This form is identical to the regular defun form, except that arglist is allowed to be a full Common Lisp argument list. Also, the function body is enclosed in an implicit block called name; see Blocks and Exits.

Macro: cl-iter-defun name arglist body…

This form is identical to the regular iter-defun form, except that arglist is allowed to be a full Common Lisp argument list. Also, the function body is enclosed in an implicit block called name; see Blocks and Exits.

Macro: cl-defsubst name arglist body…

This is just like cl-defun, except that the function that is defined is automatically proclaimed inline, i.e., calls to it may be expanded into in-line code by the byte compiler. This is analogous to the defsubst form; cl-defsubst uses a different method (compiler macros) which works in all versions of Emacs, and also generates somewhat more efficient inline expansions. In particular, cl-defsubst arranges for the processing of keyword arguments, default values, etc., to be done at compile-time whenever possible.

Macro: cl-defmacro name arglist body…

This is identical to the regular defmacro form, except that arglist is allowed to be a full Common Lisp argument list. The &environment keyword is supported as described in Steele’s book Common Lisp, the Language. The &whole keyword is supported only within destructured lists (see below); top-level &whole cannot be implemented with the current Emacs Lisp interpreter. The macro expander body is enclosed in an implicit block called name.

Macro: cl-function symbol-or-lambda

This is identical to the regular function form, except that if the argument is a lambda form then that form may use a full Common Lisp argument list.

Also, all forms (such as cl-flet and cl-labels) defined in this package that include arglists in their syntax allow full Common Lisp argument lists.

Note that it is not necessary to use cl-defun in order to have access to most CL features in your function. These features are always present; cl-defun’s only difference from defun is its more flexible argument lists and its implicit block.

The full form of a Common Lisp argument list is

(var…
 &optional (var initform svar)…
 &rest var
 &key ((keyword var) initform svar)…
 &aux (var initform)…)

Each of the five argument list sections is optional. The svar, initform, and keyword parts are optional; if they are omitted, then ‘(var)’ may be written simply ‘var’.

The first section consists of zero or more required arguments. These arguments must always be specified in a call to the function; there is no difference between Emacs Lisp and Common Lisp as far as required arguments are concerned.

The second section consists of optional arguments. These arguments may be specified in the function call; if they are not, initform specifies the default value used for the argument. (No initform means to use nil as the default.) The initform is evaluated with the bindings for the preceding arguments already established; (a &optional (b (1+ a))) matches one or two arguments, with the second argument defaulting to one plus the first argument. If the svar is specified, it is an auxiliary variable which is bound to t if the optional argument was specified, or to nil if the argument was omitted. If you don’t use an svar, then there will be no way for your function to tell whether it was called with no argument, or with the default value passed explicitly as an argument.

The third section consists of a single rest argument. If more arguments were passed to the function than are accounted for by the required and optional arguments, those extra arguments are collected into a list and bound to the “rest” argument variable. Common Lisp’s &rest is equivalent to that of Emacs Lisp. Common Lisp accepts &body as a synonym for &rest in macro contexts; this package accepts it all the time.

The fourth section consists of keyword arguments. These are optional arguments which are specified by name rather than positionally in the argument list. For example,

(cl-defun foo (a &optional b &key c d (e 17)))

defines a function which may be called with one, two, or more arguments. The first two arguments are bound to a and b in the usual way. The remaining arguments must be pairs of the form :c, :d, or :e followed by the value to be bound to the corresponding argument variable. (Symbols whose names begin with a colon are called keywords, and they are self-quoting in the same way as nil and t.)

For example, the call (foo 1 2 :d 3 :c 4) sets the five arguments to 1, 2, 4, 3, and 17, respectively. If the same keyword appears more than once in the function call, the first occurrence takes precedence over the later ones. Note that it is not possible to specify keyword arguments without specifying the optional argument b as well, since (foo 1 :c 2) would bind b to the keyword :c, then signal an error because 2 is not a valid keyword.

You can also explicitly specify the keyword argument; it need not be simply the variable name prefixed with a colon. For example,

(cl-defun bar (&key (a 1) ((baz b) 4)))

specifies a keyword :a that sets the variable a with default value 1, as well as a keyword baz that sets the variable b with default value 4. In this case, because baz is not self-quoting, you must quote it explicitly in the function call, like this:

(bar :a 10 'baz 42)

Ordinarily, it is an error to pass an unrecognized keyword to a function, e.g., (foo 1 2 :c 3 :goober 4). You can ask Lisp to ignore unrecognized keywords, either by adding the marker &allow-other-keys after the keyword section of the argument list, or by specifying an :allow-other-keys argument in the call whose value is non-nil. If the function uses both &rest and &key at the same time, the “rest” argument is bound to the keyword list as it appears in the call. For example:

(cl-defun find-thing (thing &rest rest &key need &allow-other-keys)
  (or (apply 'cl-member thing thing-list :allow-other-keys t rest)
      (if need (error "Thing not found"))))

This function takes a :need keyword argument, but also accepts other keyword arguments which are passed on to the cl-member function. allow-other-keys is used to keep both find-thing and cl-member from complaining about each others’ keywords in the arguments.

The fifth section of the argument list consists of auxiliary variables. These are not really arguments at all, but simply variables which are bound to nil or to the specified initforms during execution of the function. There is no difference between the following two functions, except for a matter of stylistic taste:

(cl-defun foo (a b &aux (c (+ a b)) d)
  body)

(cl-defun foo (a b)
  (let ((c (+ a b)) d)
    body))

Argument lists support destructuring. In Common Lisp, destructuring is only allowed with defmacro; this package allows it with cl-defun and other argument lists as well. In destructuring, any argument variable (var in the above example) can be replaced by a list of variables, or more generally, a recursive argument list. The corresponding argument value must be a list whose elements match this recursive argument list. For example:

(cl-defmacro dolist ((var listform &optional resultform)
                   &rest body)
  …)

This says that the first argument of dolist must be a list of two or three items; if there are other arguments as well as this list, they are stored in body. All features allowed in regular argument lists are allowed in these recursive argument lists. In addition, the clause ‘&whole var’ is allowed at the front of a recursive argument list. It binds var to the whole list being matched; thus (&whole all a b) matches a list of two things, with a bound to the first thing, b bound to the second thing, and all bound to the list itself. (Common Lisp allows &whole in top-level defmacro argument lists as well, but Emacs Lisp does not support this usage.)

One last feature of destructuring is that the argument list may be dotted, so that the argument list (a b . c) is functionally equivalent to (a b &rest c).

If the optimization quality safety is set to 0 (see Declarations), error checking for wrong number of arguments and invalid keyword arguments is disabled. By default, argument lists are rigorously checked.